#!/usr/bin/env python3
# -*- coding: utf-8 -*-
"""自定义异常类模块

此模块定义了应用程序中使用的自定义异常类，用于标准化错误响应格式和处理流程。
"""

class APIException(Exception):
    """API异常基类
    
    所有自定义API异常都应继承自此类
    """
    def __init__(self, status_code: int, detail: str, error_type: str = "api_error"):
        """
        初始化API异常
        
        :param status_code: HTTP状态码
        :param detail: 错误详情
        :param error_type: 错误类型
        """
        self.status_code = status_code
        self.detail = detail
        self.error_type = error_type
        super().__init__(detail)


class ValidationException(APIException):
    """验证异常
    
    用于处理请求参数验证失败的情况
    """
    def __init__(self, detail: str):
        """
        初始化验证异常
        
        :param detail: 验证失败详情
        """
        super().__init__(status_code=400, detail=detail, error_type="validation_error")


class ResourceNotFoundException(APIException):
    """资源未找到异常
    
    用于处理请求的资源不存在的情况
    """
    def __init__(self, detail: str = "请求的资源不存在"):
        """
        初始化资源未找到异常
        
        :param detail: 错误详情
        """
        super().__init__(status_code=404, detail=detail, error_type="resource_not_found")


class InternalServerException(APIException):
    """内部服务器异常
    
    用于处理服务器内部错误
    """
    def __init__(self, detail: str = "服务器内部错误"):
        """
        初始化内部服务器异常
        
        :param detail: 错误详情
        """
        super().__init__(status_code=500, detail=detail, error_type="internal_server_error")


class ServiceUnavailableException(APIException):
    """服务不可用异常
    
    用于处理服务暂时不可用的情况
    """
    def __init__(self, detail: str = "服务暂时不可用"):
        """
        初始化服务不可用异常
        
        :param detail: 错误详情
        """
        super().__init__(status_code=503, detail=detail, error_type="service_unavailable")


class AuthenticationException(APIException):
    """认证异常
    
    用于处理认证失败的情况
    """
    def __init__(self, detail: str = "认证失败"):
        """
        初始化认证异常
        
        :param detail: 错误详情
        """
        super().__init__(status_code=401, detail=detail, error_type="authentication_error")


class AuthorizationException(APIException):
    """授权异常
    
    用于处理授权失败的情况
    """
    def __init__(self, detail: str = "没有权限执行此操作"):
        """
        初始化授权异常
        
        :param detail: 错误详情
        """
        super().__init__(status_code=403, detail=detail, error_type="authorization_error")